OfficeTalk: Customizing the Word 2007 Fluent Ribbon is as Easy as 1-2-3 (Part 1 of 2)

Article
05/23/2014

This content is no longer actively maintained. It is provided as is, for anyone who may still be using these technologies, with no warranties or claims of accuracy with regard to the most recent product version or service release.

Summary: Explore scenarios using the free Custom UI Editor in part one of this two-part series. It is a must for developers creating custom user interfaces with the Microsoft Office Fluent Ribbon.

Frank Rice, Microsoft Corporation

April 2008

Applies to: Microsoft Office Word 2007

Contents

Overview
Introducing the Custom UI Editor
Creating a Simple Button in Word 2007
Conclusion

Overview

Much has been written about the Microsoft Office 2007 Fluent Ribbon User Interface (hereafter known simply as the Ribbon). The Office Fluent User Interface Developer Portal on the Microsoft Developer Network includes a plethora of information on extending the Ribbon. Customizing the Ribbon uses both XML to define the structure of the Ribbon and programming procedures known as callbacks to give the Ribbon its functionality.

Generally, you create a custom Ribbon in a Microsoft Office application in a couple of ways. Creating a custom Ribbon for a single document entails modifying an Office Open XML format file in the Office application. An Open XML format file is a zip container containing folders, files, and relationships that define the Microsoft Office application document.

To create a custom Ribbon this way, you first rename the document by adding a .zip to the filename, and then add a folder and file that contains the Ribbon XML code to the zip container. Next, you modify a package part to establish a relationship between the newly added file and the other files in the container. As stated earlier, this XML contains element attributes that point to callback procedures which gives the Ribbon its functionality. To add callback procedures to the document, you open the Visual Basic Editor and create Visual Basic for Applications (VBA) procedures. Then after renaming, saving, closing, and then reopening the document, you have a customized Ribbon specific to that document. You can also do this for templates that you make available to other users.

Another way to create a custom Ribbon that is more readily accessible is to create an Add-in that is added to Word 2007. This way, any document that you create in Word inherits the custom Ribbon. The easiest way to do this is to create the Add-in as a project in Microsoft Visual Studio. The Visual Studio Tools for the Microsoft Office system is a free application that contains a Ribbon template so you can add a customizable Ribbon to an Office project quickly.

Note

You can find more information on these methods in the 3-part series of articles titled Customizing the 2007 Office Fluent Ribbon for Developers.

However, in this two-part column, I will confine the discussion to creating a custom Ribbon for a single document. The procedure that I described previously is tedious and can result in a corrupt document if the folder and file are not added to the correct location or if the relationship is not defined correctly. In this column, I will demonstrate using a cool, free tool that makes creating customized Ribbon in documents a breeze.

Note

Because Microsoft Office Access 2007 files are not Open XML format container files, the Custom UI Editor will not allow you to embed XML into the database file.

Introducing the Custom UI Editor

What if, instead of having to rename the Word 2007 file, open the container, add the parts, modify the relationship, rename the container, and reopen the document, you could just write the XML, save the document, and the correct parts and relationships are automatically added to the document for you?

You can do just that with a nifty tool designed specifically to take much of the pain out of creating Ribbon customizations at the document level. And best yet, the tool is free. The Custom UI Editor is a great utility for working with Ribbon customizations stored in Office Open XML documents. The tool was written by Trang Luu who works on the Microsoft Office Fluent User Interface team and is one of the key developers of the Ribbon.

Note

The Custom UI Editor is not the only tool available to work with XML code. For example, the XML Notepad 2007 is another free tool from Microsoft that you can use when writing XML code. However, the Custom UI Editor is specifically written to customize the Ribbon in Microsoft Office applications.

Opening the Custom UI Editor reveals a simple user interface as seen in Figure 1.

Figure 1. The XML code screen in the Custom UI Editor with callouts

The Custom UI tab is where you type the XML that defines the Ribbon. All you need to do is open a Microsoft Office 2007 document from the File menu, type the XML code, save the document, and the correct parts are automatically added to the document and the relationship is created for you. Opening the document in the Microsoft Office application reveals the customized Ribbon defined in the code. Again looking at Figure 1, the code is colorful with red, blue, and burgundy lines designed to make it easier for you to follow the structure of the code.

There is also a Validate icon on the toolbar that you use to test the XML to ensure that it is well-formed before adding it to your document. In addition, clicking the Generate Callbacks icon on the toolbar causes the tool to examine the XML and generate callbacks, with the correct signatures, for any actions defined in the XML. You then copy and paste the empty callback procedures into the VBA Editor in your document, add the functionality code, and you have every thing you need to customize the Ribbon.

The Insert Icons icon on the toolbar allows you to associate icons with the controls on the Ribbon. To do so, you first add the image to the editor and then apply the name of the image file to the image attribute. After saving the document, the editor adds the image file to the container and creates the appropriate relationships for you.

If you find yourself retyping parts of the XML over and over, you can also create a template containing the XML code and add it to the editor. Then by selecting the template from the Sample menu in the editor, the custom XML is displayed for you. You will see how to do this later in this column.

I'm sure that you are anxious to get started so let's create simple button in Word 2007.

Creating a Simple Button in Word 2007

In the following procedures, you will create a Word 2007 document and then by using the Custom UI Editor, add a button that displays a message when clicked.

Create a simple button in Word 2007

Start Word 2007 and save the default document to your desktop or another convenient location as a macro-enabled (.docm) file.
Start the Custom UI Editor.
On the File menu, click Open, navigate to the document you created, and click Open.

In the Custom UI tab, type or paste the following XML.

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui">
  <ribbon startFromScratch="false">
    <tabs>
      <tab id="customTab" label="My Tab">
        <group id="sampleGroup" label="Sample Group">
          <button id="button1" label="Click Me" 
            size="normal" />
        </group >
      </tab>
    </tabs>
  </ribbon>
</customUI>

Now to make sure that you haven't made any mistakes in your code, on the toolbar, click Validate. If all is well, you will see the screen as shown in Figure 2. Otherwise check your code against the listing and make any necessary corrections.

Note

XML is case-sensitive so if you receive errors, be sure and check the casing of the elements and attributes in your XML. To see the effects of this, change the startFromScratch attribute to startfromScratch and then click the Validate icon. Correct the attribute and continue with the procedures.

Figure 2. This message is displayed for well-formed XML
To see the results of your code, click the Save button on the toolbar. This automatically adds the folder and XML file to the document container and creates the relationship for you.
Open the Word 2007 document that you created earlier. You see the My Tab tab on the right of the other tabs. On the My Tab tab, you see the Sample Group group and Click Me button.
Click the Click Me button. Notice that nothing happens because you haven't defined or created a callback procedure for the button. Close the document.
Returning to the Custom UI Editor, add the following attribute to the button's XML after the size="normal" attribute.
```
onAction="myButtonMacro"
```
Test that the updated XML is well-formed and then create the callback signature for the button by clicking the Generate Callback icon on the toolbar. This action creates the following callback procedure.
```
' Callback for button1 onAction
Sub myButtonMacro(control as IRibbonControl)
End Sub
```
Copy the code to the Clipboard.
Add the callback to the Visual Basic Editor by opening the document in Word 2007.
On the Developer tab, click Visual Basic. If you don't see the Developer tab, do the following:
1. Click the Microsoft Office button (located in the upper-left of the document screen) and then click Word Options.
2. On the Popular tab, select the Show Developer tab in the Ribbon option.
On the Insert menu, click Module.
In the Module code screen, paste the callback code you copied previously.

Modify the code as follows.

Sub myButtonMacro(control as IRibbonControl)
   Msgbox "You clicked " & control.Id
End Sub

On the File menu, click Save and then close the VBA Editor.
Click My Tab and then click the button. The message box shown in Figure 3 is displayed. Notice that the Id of the button is displayed corresponding to control.Id in the code.

Figure 3. When the button is clicked, a message box with the button Id is displayed

Conclusion

In part one of this series of columns you saw how easy it is to create a custom Ribbon. In part two, you will see that it is equally easy to add images to the Ribbon as well as adding templates to the Custom UI Editor.

OfficeTalk: Customizing the Word 2007 Fluent Ribbon is as Easy as 1-2-3 (Part 1 of 2)

Overview

Introducing the Custom UI Editor

Creating a Simple Button in Word 2007

Create a simple button in Word 2007

Conclusion

Additional resources